- Description:
This key represents a single value option within a structure, defining the data format and appearance for content editors.
- Appears in:
- Type:
Object- Properties:
This key toggles whether CloudCannon should treat an entry in the
valuesarray as the default option for your Object or Array input.Setting this key to
truewill mark this entry as the default option for your Object or Array input. If multiple entries in thevaluesarray are set totrue, CloudCannon will use the first entry. If CloudCannon cannot determine the type of an entry within thevaluesarray based on theid_keyor matching inputs acrossvalues[*].valueobjects, it will fall back to the default entry.Defaults to:
falseShow examplesHide examples
In this example, we want the entry labelled
Employeeto be our default option for populating inputs configured with thestaffStructure.Copied to clipboard_structures: staff: style: modal values: - label: Employee default: true value: name: job_description: profile_picture: - label: Manager value: name: job_description: profile_picture: url:{ "_structures": { "staff": { "style": "modal", "values": [ { "label": "Employee", "default": true, "value": { "name": null, "job_description": null, "profile_picture": null } }, { "label": "Manager", "value": { "name": null, "job_description": null, "profile_picture": null, "url": null } } ] } } }This key defines short descriptive text for editors shown in the Data Editor for expanded values matching this Structure value.
Has no default.
Supports a limited set of Markdown: links, bold, italic, subscript, superscript, and inline code elements are allowed.
This key defines the documentation link at the top of a Collection browser.
Collection documentation is useful for assisting your team members.
Show examplesHide examples
In this example, the documentation link for the
dataCollection goes to CloudCannon Documentation.Copied to clipboardcollections_config: data: documentation: url: https://cloudcannon.com/documentation/ text: CloudCannon Documentation icon: star{ "collections_config": { "data": { "documentation": { "url": "https://cloudcannon.com/documentation/", "text": "CloudCannon Documentation", "icon": "star" } } } }This key defines the order and custom grouping for inputs within a Structure.
The value is an array of group objects. Each group object can contain a
heading,comment,collapsed, andinputsarray.Show examplesHide examples
In this example, we want to separate the inputs into two groups with descriptive headings:
titleandsubtitleunder theTitlesheading, andauthorunder theDetailsheading.Copied to clipboard_structures: article_information: values: - label: Blog value: title: subtitle: author: groups: - heading: Titles inputs: - title - subtitle - heading: Details inputs: - author{ "_structures": { "article_information": { "values": [ { "label": "Blog", "value": { "title": null, "subtitle": null, "author": null }, "groups": [ { "heading": "Titles", "inputs": [ "title", "subtitle" ] }, { "heading": "Details", "inputs": [ "author" ] } ] } ] } } }This key toggles whether CloudCannon will hide inputs that are not present in a given value from a Structure from the Data Editor.
Setting this key to
truewill hide inputs that are not present in a given value from a Structure from the Data Editor. Hiding these inputs does not delete the data. You can see non-structure data keys by opening a file in the Source Editor. This key has no effect ifremove_extra_inputsistrue.You can also configure this behavior for all values of a Structure using
hide_extra_inputsinside_structures.*.Defaults to:
falseThis key defines an icon used when displaying the structure (defaults to either
format_list_bulletedfor items in arrays, ornotesotherwise).Allowed values:
12336010k10mp11mp12mp13mp14mp15mp16mpand 3574 more.Show examplesHide examples
In this example, CloudCannon will display the
articleicon for the entry labeledBlogin thearticle_informationStructure.Copied to clipboard_structures: article_information: values: - label: Blog icon: article{ "_structures": { "article_information": { "values": [ { "label": "Blog", "icon": "article" } ] } } }This key defines the string used to identify a given Structure value when refering to it from other input configuration.
Show examplesHide examples
In this example, we have configured the
blog_postID for the entry labeledBlogin thearticle_informationStructure.Copied to clipboard_structures: article_information: values: - label: Blog id: blog_post{ "_structures": { "article_information": { "values": [ { "label": "Blog", "id": "blog_post" } ] } } }This key defines the path to an image in your source files used when displaying the structure value.
Can be either a source (has priority) or output path.
Show examplesHide examples
In this example, we have configured the
/images/blog-icon.pngimage for the entry labeledBlogin thearticle_informationStructure.Copied to clipboard_structures: article_information: values: - label: Blog image: /images/blog-icon.png{ "_structures": { "article_information": { "values": [ { "label": "Blog", "image": "/images/blog-icon.png" } ] } } }This key defines which inputs are available at a given level of the configuration cascade.
This key has no default.
If undefined at higher levels of the configuration cascade,
_inputswill default to any values configured in the CloudCannon configuration file.Show examplesHide examples
In this example, we have configured the
date_createdkey as a Date and Time Input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.Copied to clipboard_inputs: date_created: type: datetime label: Date of article creation comment: UTC +0 timezone context: open: false title: Help icon: help content: This date field will automatically populate when you create an article. hidden: false disabled: true instance_value: NOW cascade: true options: timezone: Etc/UTC{ "_inputs": { "date_created": { "type": "datetime", "label": "Date of article creation", "comment": "UTC +0 timezone", "context": { "open": false, "title": "Help", "icon": "help", "content": "This date field will automatically populate when you create an article." }, "hidden": false, "disabled": true, "instance_value": "NOW", "cascade": true, "options": { "timezone": "Etc/UTC" } } } }In this example, we have configured the
blog_tagskey as a Multiselect Input in theblogCollection.Copied to clipboardcollections_config: blog: _inputs: blog_tags: type: multiselect label: Blog type comment: Select a blog type context: open: false title: Help icon: help content: | Blog tags help our users filter articles by topic. options: values: - Opinion - Feature - Resource{ "collections_config": { "blog": { "_inputs": { "blog_tags": { "type": "multiselect", "label": "Blog type", "comment": "Select a blog type", "context": { "open": false, "title": "Help", "icon": "help", "content": "Blog tags help our users filter articles by topic.\n" }, "options": { "values": [ "Opinion", "Feature", "Resource" ] } } } } } }This key defines globs that filter which files CloudCannon should use for Input configuration.
Values in this array are relative to the root of your repository (i.e.,
/, not the value ofsource) and must end in the file extension.cloudcannon.inputs.yml.You can use this key anywhere you would use the
_inputskey in the configuration cascade.This key has no default.
Show examplesHide examples
In this example, we have several Input Configuration Files in the
.cloudcannon/inputs/folder, with each file containing multiple Input definitions. The value of the_inputs_from_globkey tells CloudCannon to only use theseo.cloudcannon.inputs.ymlandblog-details.cloudcannon.inputs.ymlfiles in that folder.Copied to clipboardcollections_config: posts: path: content/posts icon: event inputs_from_glob: - /.cloudcannon/inputs/seo.cloudcannon.inputs.yml - /.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml{ "collections_config": { "posts": { "path": "content/posts", "icon": "event", "inputs_from_glob": [ "/.cloudcannon/inputs/seo.cloudcannon.inputs.yml", "/.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml" ] } } }Copied to clipboardseo_title: type: text options: required: true max_length: 50 seo_description: type: textarea options: show_count: true required: true max_length: 125 seo_image: type: image options: path: uploads: images accepts_mime_types: - image/png - image/jpeg required: true pattern: (?i)\.(jpe?g|png)$ pattern_message: Please select a JPG or PNG image file{ "seo_title": { "type": "text", "options": { "required": true, "max_length": 50 } }, "seo_description": { "type": "textarea", "options": { "show_count": true, "required": true, "max_length": 125 } }, "seo_image": { "type": "image", "options": { "path": { "uploads": "images" }, "accepts_mime_types": [ "image/png", "image/jpeg" ], "required": true, "pattern": "(?i)\\.(jpe?g|png)$", "pattern_message": "Please select a JPG or PNG image file" } } }This key defines the display name for a given value in a Structure.
The name will appear in the + Add button dropdown below an Object or Array input or in the Structures modal (if configured).
By default, this key falls back to
unknown.Show examplesHide examples
In this example, we want two value options for our
staffstructure: one calledManagerand one calledEmployee.Copied to clipboard_structures: staff: values: - label: Employee value: name: job_description: profile_picture: - label: Manager value: name: job_description: profile_picture: url:{ "_structures": { "staff": { "values": [ { "label": "Employee", "value": { "name": null, "job_description": null, "profile_picture": null } }, { "label": "Manager", "value": { "name": null, "job_description": null, "profile_picture": null, "url": null } } ] } } }This key defines the appearance of a Card when choosing an item to create. This uses
previewas a base, and keys inside this object are overrides.You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.
For more information about previews, please read our documentation on configuring card previews.
Show examplesHide examples
In this example, we have configured the appearance of Cards in inputs using the Structure
staffwhen adding items.Copied to clipboard_structures: staff: values: - value: _type: Employee name: job_description: profile_picture: picker_preview: text: - key: name - Employee subtext: - key: job_description - Description of position image: - key: profile_picture icon: support_agent - value: _type: Manager name: job_description: profile_picture: url: picker_preview: text: - key: name - Manager subtext: - key: job_description - Description of position image: - key: profile_picture icon: face{ "_structures": { "staff": { "values": [ { "value": { "_type": "Employee", "name": null, "job_description": null, "profile_picture": null }, "picker_preview": { "text": [ { "key": "name" }, "Employee" ], "subtext": [ { "key": "job_description" }, "Description of position" ], "image": [ { "key": "profile_picture" } ], "icon": "support_agent" } }, { "value": { "_type": "Manager", "name": null, "job_description": null, "profile_picture": null, "url": null }, "picker_preview": { "text": [ { "key": "name" }, "Manager" ], "subtext": [ { "key": "job_description" }, "Description of position" ], "image": [ { "key": "profile_picture" } ], "icon": "face" } } ] } } }This key defines which order input groups and ungrouped inputs appear in.
Defaults to:
falseThis key defines the appearance of a Card.
You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.
For more information about previews, please read our documentation on configuring card previews.
Show examplesHide examples
In this example, we have configured the appearance of file Cards in the Collection browser.
Copied to clipboardcollections_config: blog: preview: text: - key: title subtext: - key: author icon: edit_note icon_color: - key: color - '#ff0000' image: - key: image metadata: - template: - url - icon: event text: - template: Published on {date|date_long} gallery: - key: featured_image{ "collections_config": { "blog": { "preview": { "text": [ { "key": "title" } ], "subtext": [ { "key": "author" } ], "icon": "edit_note", "icon_color": [ { "key": "color" }, "#ff0000" ], "image": [ { "key": "image" } ], "metadata": [ { "template": [ "url" ] }, { "icon": "event", "text": [ { "template": "Published on {date|date_long}" } ] } ], "gallery": [ { "key": "featured_image" } ] } } } }In this example, we have configured the appearance of Cards in inputs using the Structure
staff.Copied to clipboard_structures: staff: values: - value: _type: Employee name: job_description: profile_picture: preview: text: - key: name - Employee subtext: - key: job_description - Description of position image: - key: profile_picture icon: support_agent - value: _type: Manager name: job_description: profile_picture: url: preview: text: - key: name - Manager subtext: - key: job_description - Description of position image: - key: profile_picture icon: face{ "_structures": { "staff": { "values": [ { "value": { "_type": "Employee", "name": null, "job_description": null, "profile_picture": null }, "preview": { "text": [ { "key": "name" }, "Employee" ], "subtext": [ { "key": "job_description" }, "Description of position" ], "image": [ { "key": "profile_picture" } ], "icon": "support_agent" } }, { "value": { "_type": "Manager", "name": null, "job_description": null, "profile_picture": null, "url": null }, "preview": { "text": [ { "key": "name" }, "Manager" ], "subtext": [ { "key": "job_description" }, "Description of position" ], "image": [ { "key": "profile_picture" } ], "icon": "face" } } ] } } }This key toggles whether CloudCannon will remove empty nested inputs from an Object Input or Array Input using a given value from a Structure before persisting them to your file.
Setting this key to
truewill remove empty nested inputs from an Object Input or Array Input using a given value from a Structure before persisting them to your file. CloudCannon considers an input to be empty when its value isnull,' ', or undefined. If this key is true, empty inputs will be visible in the Data Editor but not the Source Editor. For this key to function, you must also configureid_keyfor the Structure, as removing inputs prevents CloudCannon from comparing Structure values.You can also configure this behavior for all values of a Structure using
remove_empty_inputsinside_structures.*.Defaults to:
falseThis key toggles whether CloudCannon will remove inputs that are not present in a given value from a Structure from a file before loading it in an Editing Interface.
Setting this key to
truewill remove inputs that are not present in a given value from a Structure from a file before loading it in an Editing Interface. Non-Structure inputs will not be visible in the Visual Editor, Content Editor, or Data Editor, and saving the file will remove them from the file before persisting the changes to your Git repository.You can also configure this behavior for all values of a Structure using
remove_extra_inputsinside_structures.*.Defaults to:
trueThis key toggles whether CloudCannon will reorder inputs in a file to match the order defined in a given value from a Structure.
Setting this key to
falsewill preserve the existing order of inputs in a file, regardless of the order defined in the Structure value.By default, this key is
true(i.e., inputs are reordered to match the Structure value).You can also configure this behavior for all values of a Structure using
reorder_inputsinside_structures.*.Defaults to:
trueThis key defines defines fixed data sets to populate Select and Multiselect inputs at a given level of the configuration cascade.
This key has no default.
If undefined at higher levels of the configuration cascade,
_select_datawill default to any values configured in the CloudCannon configuration file.For more information, please read our documentation on Select and Multiselect inputs.
Show examplesHide examples
In this example, we have configured the
blog_tagsMultiselect input for theblogCollection.Copied to clipboardcollections_config: blog: _select_data: blog_topics: - Opinion - Feature - Resource{ "collections_config": { "blog": { "_select_data": { "blog_topics": [ "Opinion", "Feature", "Resource" ] } } } }This key defines which structures are available for Object inputs and Array inputs at a given level of the configuration cascade.
This key has no default.
If undefined at higher levels of the configuration cascade,
_structureswill default to any values configured in the CloudCannon configuration file.For more information, please read our documentation on structures.
Show examplesHide examples
In this example, we want to populate an Array input in the
blogCollection with Related Articles, including thename,description, andurlfields.Copied to clipboardcollections_config: blog: _structures: related_articles: style: select values: - preview: text: - key: name subtext: - key: url value: name: description: url:{ "collections_config": { "blog": { "_structures": { "related_articles": { "style": "select", "values": [ { "preview": { "text": [ { "key": "name" } ], "subtext": [ { "key": "url" } ] }, "value": { "name": null, "description": null, "url": null } } ] } } } } }In this example, we want to populate an Array input with Staff members, including the
name,job_description, andprofile_picturefields for all staff types, and theurlfield for Managers only.Copied to clipboard_structures: staff: style: modal hide_extra_inputs: false values: - value: _type: Employee name: job_description: profile_picture: preview: text: - key: name - Employee subtext: - key: job_description - Description of position image: - key: profile_picture icon: support_agent - value: _type: Manager name: job_description: profile_picture: url: preview: text: - key: name - Manager subtext: - key: job_description - Description of position image: - key: profile_picture icon: face{ "_structures": { "staff": { "style": "modal", "hide_extra_inputs": false, "values": [ { "value": { "_type": "Employee", "name": null, "job_description": null, "profile_picture": null }, "preview": { "text": [ { "key": "name" }, "Employee" ], "subtext": [ { "key": "job_description" }, "Description of position" ], "image": [ { "key": "profile_picture" } ], "icon": "support_agent" } }, { "value": { "_type": "Manager", "name": null, "job_description": null, "profile_picture": null, "url": null }, "preview": { "text": [ { "key": "name" }, "Manager" ], "subtext": [ { "key": "job_description" }, "Description of position" ], "image": [ { "key": "profile_picture" } ], "icon": "face" } } ] } } }This key defines globs that filter which files CloudCannon should use for Structure configuration.
Values in this array are relative to the root of your repository (i.e.,
/, not the value ofsource) and must end in the file extension.cloudcannon.structures.yml.You can use this key anywhere you would use the
_structureskey in the configuration cascade.Please see our documentation on values_from_glob for defining individual Structure values in a split Configuration File.
This key has no default.
Show examplesHide examples
In this example, we have several Structure Configuration Files in the
.cloudcannon/structures/folder. The value of the_structures_from_globkey tells CloudCannon to use thestaffMembers.cloudcannon.structures.ymlfile in that folder.Copied to clipboard_structures_from_glob: - /.cloudcannon/structures/staffMembers.cloudcannon.structures.yml{ "_structures_from_glob": [ "/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml" ] }Copied to clipboardstaff: style: modal values: - label: Employee value: name: job_description: profile_picture: - label: Manager value: name: job_description: profile_picture: url:{ "staff": { "style": "modal", "values": [ { "label": "Employee", "value": { "name": null, "job_description": null, "profile_picture": null } }, { "label": "Manager", "value": { "name": null, "job_description": null, "profile_picture": null, "url": null } } ] } }This key toggles whether CloudCannon should create tabs in the Data Editor if you have two layers of nested object within your Structure.
Setting this key to
truewill create tabs in the Data Editor for two layers of nested objects within your Structure.By default, this key is
false(i.e., Object and Array inputs using this Structure option are not tabbed).Defaults to:
falseShow examplesHide examples
In this example, we want the
contentandstylekeys in our Structure to be tabs at the top of the Data Editor, with thetitleandtext, andcolorandfontkeys nested within those tabs respectively.Copied to clipboard_structures: components: values: - label: Component tabbed: true value: content: title: text: style: color: font:{ "_structures": { "components": { "values": [ { "label": "Component", "tabbed": true, "value": { "content": { "title": null, "text": null }, "style": { "color": null, "font": null } } } ] } } }This key defines which tags are associated with a given value in a Structure.
You can use tags to group and filter Structure options when selecting from a modal.
This key has no default.
Show examplesHide examples
In this example we have three options for the
page_componentsStructure:Hero Component,Feature Component, andVideo Component. We can search the Structure modal using theimage,text,button, andvideotags to filter Structure values.Copied to clipboard_structures: page_components: style: modal values: - label: Hero Component tags: - image - text value: title: description: image_path: link: text: url: - label: Feature Component tags: - image - text - button value: image_path: title: description: button: link: text: reversed_layout: false - label: Video Component tags: - image - video value: image_path: videoUrl:{ "_structures": { "page_components": { "style": "modal", "values": [ { "label": "Hero Component", "tags": [ "image", "text" ], "value": { "title": null, "description": null, "image_path": null, "link": { "text": null, "url": null } } }, { "label": "Feature Component", "tags": [ "image", "text", "button" ], "value": { "image_path": null, "title": null, "description": null, "button": { "link": null, "text": null }, "reversed_layout": false } }, { "label": "Video Component", "tags": [ "image", "video" ], "value": { "image_path": null, "videoUrl": null } } ] } } }This key defines which nested inputs the Structure value should add to an Object or Array input.
You must define this key for the Structure value to function.
Nested keys can be any input you require in your Object or Array.
For more information, please read our documentation on configuring an Object input and configuring and Array input.
Show examplesHide examples
In this example we want to populate the
detailsObject input with the nested keystitle,subtitle, andauthorwe have defined under thevalues.valuekey.Copied to clipboard_structures: article_information: values: - label: Blog value: title: subtitle: author: _inputs: details: type: object options: structures: _structures.article_information{ "_structures": { "article_information": { "values": [ { "label": "Blog", "value": { "title": null, "subtitle": null, "author": null } } ] } }, "_inputs": { "details": { "type": "object", "options": { "structures": "_structures.article_information" } } } }- Examples: